Because buffer allocation (especially direct buffer allocation) has a specific, significant performance impact, buffer pooling is essential for maximizing performance in an I/O-intensive application. For this reason, XNIO provides extensive support for pooling buffers.
In order to effectively pool a resource, the pool consumer must have a mechanism by which pooled resources can be returned to the pool. Because of the nature of the JVM GC cycle, using automatic cleanup mechanisms such as finalization are not only ineffective, but actually detrimental to performance and functionality; for example, it is possible to artificially deplete the direct buffer pool because outstanding allocated direct buffer objects remain in existence due to GC delays.
The XNIO buffer pool API utilizes two classes for this purpose: org.xnio.Pool and org.xnio.Pooled. The former represents the pool itself, and the latter is a holder for a pooled resource type.
If an item is allocated from a pool which is empty, a org.xnio.PoolDepletedException will result. This is a runtime exception, but should be gracefully handled nevertheless (though in many cases the only acceptable behavior is the cancellation of whatever the current operation is).
Items allocated from pools must be freed or discarded. Normally freeing items is the correct action to take. Items should only be discarded if it is impossible to determine whether the item is still in use. If the discard() method is called, a phantom reference is created to track the item, and the item is lazily returned to the pool once all references to it have been cleared; this is a potentially expensive operation so it should be utilized only sparingly if at all.
The free() and discard() methods are idempotent. Furthermore, if either method is called, subsequent calls to either method are ignored.
It is critical that buffers not be accessed after their corresponding Pooled object is freed or discarded. Doing so may cause difficult-to-debug data corruption.
The pool API is only currently implemented for buffers, however the API used is generally applicable to many types of resources and may be used for other item types beyond buffers. The type signatures for these interfaces are intended to be read fluently, e.g. Pool<ByteBuffer> is read as "a pool of byte buffers" and Pooled<ByteBuffer> is read as "a pooled byte buffer".